feat(socratic-recovery): pin a fixed second level for the question tree#497
Merged
rdmueller merged 2 commits intoMay 17, 2026
Merged
Conversation
Closes LLM-Coding#493, LLM-Coding#494, LLM-Coding#495. Across four reverse-engineering runs on the same codebase the question tree came out at 105 / 60 / 57 leaves, with whole role-sections silently dropped. "Anchors as guides" does not constrain the shape. This pins the tree's second level to a fixed, enumerated node set so Q-IDs are stable and trees from different runs diff node-by-node. The fixed second level (emitted on every run, even when a node's only leaf is [OPEN] or [ANSWERED: not applicable]): - Q1.1-Q1.6 six PRD elements - Q2.1-Q2.6 six specification categories - Q3.1-Q3.12 the twelve arc42 chapters, in arc42 order - Q4.1-Q4.8 the eight ISO/IEC 25010 characteristics; Q4.9 priority - Q5.1-Q5.5 five risk categories Free, code-driven decomposition continues only below the fixed level. LLM-Coding#493 — contracts.json: rewrote the socratic-code-theory-recovery card (template + templateDe) as the canonical enumeration. LLM-Coding#494 — brownfield page (EN/DE): Phase 1 prose, the copy-paste Phase 1 prompt, the cheat-sheet prompt, and the OPEN_QUESTIONS rule (always one section per Ask role, empty ones included). LLM-Coding#495 — the skill: phase-1-question-tree prompt, SKILL.md, and the references (arc42, iso-25010, cockburn-use-cases, output-schema, examples) reframed from "guides" to the fixed level. Named use-case sub-trees now nest under their fixed node — Q2.PUC.* -> Q2.2.PUC.*, Q2.SUC.* -> Q2.3.SUC.* — and the socratic-recovery-skill page (EN/DE) is brought in line. Plugin mirror auto-synced by the pre-commit hook. The last contract bullet drops "with Q-ID traceability" to stay consistent with the merged LLM-Coding#491 (Q-IDs are build-time only, not written into synthesized docs). docs/all-anchors.adoc regenerated (was stale — missing recent anchors). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (14)
WalkthroughDie PR konkretisiert das Socratic Code-Theory Recovery-Verfahren durch eine fixierte zweite Ebene des Fragenbaums (Q1.1–Q5.5) mit stabilen Q-IDs über Dokumentationen, Prompts, Referenzmaterialien und Skill-Definitionen hinweg. Dadurch wird die vorherige freie Zerlegung durch eine enumerierte, maschinenüberprüfbare Struktur ersetzt, die konsistente Ausgaben über mehrere Läufe ermöglicht. ChangesFixierte zweite Ebene des Question-Tree mit stabilen Q-IDs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 10
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
skill/socratic-code-theory-recovery/references/examples.md (1)
167-188:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winKritisches Problem: Duplizierte Q-ID Q5.1.
Sowohl Zeile 167 als auch Zeile 178 verwenden
Q5.1als Fragenidentifikator:
- Zeile 167:
### Q5.1: What test debt exists?- Zeile 178:
### Q5.1: What technical debt is the team already tracking?Q-IDs müssen eindeutig sein, da sie als stabile Build-Zeit-Identifikatoren dienen (laut PR-Zielen und SKILL.md). Die zweite Frage sollte wahrscheinlich
Q5.2sein.🔧 Vorgeschlagene Korrektur
-### Q5.1: What technical debt is the team already tracking? +### Q5.2: What technical debt is the team already tracking?🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skill/socratic-code-theory-recovery/references/examples.md` around lines 167 - 188, The file contains duplicate question IDs: the headings "### Q5.1: What test debt exists?" and "### Q5.1: What technical debt is the team already tracking?" must be unique; change the second heading to "### Q5.2: What technical debt is the team already tracking?" and update any in-file references or cross-links that point to the old Q5.1 identifier (search for "Q5.1" occurrences and adjust to "Q5.2" where they refer to the second question) so build-time stable IDs remain unique.
🧹 Nitpick comments (1)
website/public/llms.txt (1)
6375-6380: ⚡ Quick winKanonische Quelle explizit referenzieren, um Enumerations-Drift zu vermeiden.
Die vollständige Zweite-Ebene-Liste ist hier dupliziert. Ein kurzer SSOT-Hinweis auf den Contract (z. B.
contracts.json/#493) reduziert Pflegefehler bei zukünftigen Änderungen.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/public/llms.txt` around lines 6375 - 6380, The duplicated fixed second-level enumeration (Q1.1–Q5.5) should be replaced with a single canonical reference to the contracts source instead of repeating the list: remove the hard-coded list in website/public/llms.txt and add a short SSOT pointer like "See canonical enumeration in contracts.json (contract `#493`)" and, if desired, a concise note that the second-level nodes are fixed (Q1.1–Q5.5) to preserve intent; ensure any mention of the second-level enumeration across the repo refers to contracts.json/#493 to avoid drift.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/brownfield-workflow.adoc`:
- Around line 69-70: Die lokal ausgeschriebene Enumeration Q1.1–Q5.5 (inkl.
Q3.1–Q3.12 und Q4.1–Q4.9) fehlt eine Verlinkung zur kanonischen
Contract-Definition; aktualisiere beide Stellen, an denen die feste Ebene
ausgeschrieben ist, so dass unmittelbar nach der Beschreibung ein klarer Verweis
auf die offizielle Contract-Quelle steht (z. B. ein eindeutiger
Contract-Identifier/URL oder ein Verweisstext wie "siehe Canonical Question
Contract <name/id>"), und ergänze optional einen kurzen Hinweis, dass Q-IDs
stabil sind (z. B. "Q3.7 = Deployment View") damit künftig kein Drift zwischen
dieser Dokumentation und dem Contract entsteht.
In `@docs/brownfield-workflow.de.adoc`:
- Around line 67-68: Die wiederholte feste Enumeration (Q1.1–Q5.5, inklusive
Q3.7 als Verteilungssicht) muss mit der kanonischen Contract-Quelle verlinkt
werden: ergänze in der kurzen Beschreibung bei "zweite Ebene ist fix" und in der
vollständigen Liste (die zweite Stelle der Wiederholung) jeweils einen
eindeutigen Verweis/Zitat (z. B. Contract-Name, Version und URL oder AsciiDoc
xref/anchor) zur offiziellen Quelle, so dass Leserinnen direkt zur autoritativen
Definition springen können und Inkonsistenzen vermieden werden.
In `@docs/socratic-recovery-skill.adoc`:
- Line 12: The document hard-codes the fixed Question Tree enumeration (Q-IDs
like Q1.1–Q5.5, the six PRD elements, twelve arc42 chapters, the eight ISO/IEC
25010 characteristics, etc.) in the prose and table sections, which breaks
Single Source of Truth; change the docs to reference and/or include the
canonical contract data instead of literal lists: replace the explicit
enumeration in the "Question Tree"/Q-IDs text and the table block that repeats
those entries with a generated include or template call that pulls the
authoritative enumeration from the canonical contract/metadata source (the same
JSON/YAML/constants that define the Q-IDs), and add a simple validation step in
the doc build to fail if the included enumeration and the contract diverge so
the "Q-IDs"/Question Tree and table remain in sync.
In `@docs/socratic-recovery-skill.de.adoc`:
- Line 12: The repeated explicit enumeration of the fixed Question Tree nodes
(the Q1.1–Q5.5 list referenced in the "Question Tree" description and the
duplicate block later) must be replaced by a canonical reference: remove the
hard-coded list text and instead reference or include the single authoritative
contract/source (the canonical contract for the Skill) so the document points to
that source for the fixed node list; update both occurrences that mention
"Q1.1–Q5.5" and the repeated fixed-node paragraph to use an AsciiDoc include or
xref to the canonical contract (or a named "Socratic Recovery Skill" contract
identifier) and keep the explanatory text about stable Q-IDs and free
decomposition unchanged.
In
`@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md`:
- Line 169: Der fehlende Language-Tag am Fenced-Code-Block verursacht MD040;
ergänze unmittelbar nach den drei Backticks des betreffenden Blockbeginns im
examples.md einen Language-Identifier (z.B. ```text oder ```markdown) damit der
Linter den Block korrekt erkennt und MD040 verschwindet; suche den ungetaggten
Block um Zeile 169 und füge den Tag ein.
- Around line 167-178: The document has two headings using the same Q-ID "Q5.1"
(the heading "### Q5.1: What test debt exists?" and the subsequent "### Q5.1:
What technical debt is the team already tracking?"), causing schema ambiguity;
fix by assigning a unique ID to the second heading (e.g., rename it to "Q5.2" or
the next sequential ID), update any internal references or cross-links that
point to the old ID, and ensure all other Q-ID headings remain unique (search
for "Q5.1" occurrences and adjust them consistently, including in any TOC or
anchors).
In
`@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.md`:
- Around line 3-4: Die Referenz auf die Prioritätsfrage ist falsch: ersetze alle
Verwendungen/Verweise von Q4.0 durch Q4.9 in diesem Skill so dass die feste
Prioritäts-Node korrekt auf Q4.9 zeigt; überprüfe alle Stellen, die IDs oder
Ausgaben generieren (z.B. die Beschreibung "fixed nodes Q4.1–Q4.8" und die
Stelle, die "Priorität" referenziert) und passe die erzeugten IDs/Labels an,
damit Outputs konsistent Q4.9 als Prioritätsknoten ausweisen.
In
`@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.md`:
- Around line 63-65: The document contradicts itself about Q-ID stability:
reconcile and clarify the numbering rules by stating that the "fixed second
level" (Q1.1–Q1.6, Q2.1–Q2.6, Q3.1–Q3.12, Q4.1–Q4.9, Q5.1–Q5.5) remains stable
across runs (e.g., Q3.7 always means Deployment View) while only the
arbitrary-depth nodes below that (examples like Q3.5.2 and any third-level+
nodes) may be renumbered per re-run; update the language where it currently says
"tree is renumbered on every re-run" to limit that statement to third-level and
deeper nodes and add a short sentence stating that fixed nodes must always be
emitted (even if only [OPEN] or [ANSWERED: not applicable]) to preserve
cross-run diffs.
In `@skill/socratic-code-theory-recovery/references/output-schema.md`:
- Around line 63-65: Die Formulierung zur Q-ID-Traceability ist inkonsistent:
halten Sie die zweite Ebene als feste, stabile Nummerierung fest (z. B.
Q1.1–Q1.6, Q3.7 = Deployment View) und entfernen oder korrigieren Sie jede
Aussage, die behauptet, diese zweite Ebene werde bei jedem Lauf „renumbered“.
Erklären Sie stattdessen klar, dass nur die dritte Ebene (z. B. Q3.5.2 und
tiefer) frei und laufzeitabhängig nummeriert wird; behalten Sie die Anweisung
bei, alle festen Knoten auch mit `[OPEN]`/`[ANSWERED: not applicable]` zu
emitten, und passen Sie Formulierungen an Q1, Q2, Q1.1, Q3.7 und Q3.5.2 an,
damit die Traceability-Beschreibung konsistent ist.
In `@website/public/llms.txt`:
- Around line 6382-6387: Die beiden Regeln sind inkonsistent: die Zeile "stop
when a leaf is answerable from one piece of code evidence or one stakeholder
fact." erlaubt `[ANSWERED]` durch Stakeholder-Fakten, während die Zeile "Each
leaf is [ANSWERED] (with file:line evidence) or [OPEN] ..." verlangt, dass
`[ANSWERED]` strikt mit `file:line` belegt ist; vereinheitliche das Dokument
indem du die erste Formulierung änderst so, dass `[ANSWERED]` nur für Antworten
mit konkretem Code-Beleg (explizit "file:line evidence") gilt und
Stakeholder-Fakten nur `[ANSWERED]` werden dürfen, wenn sie zusätzlich einen
verlinkten file:line-Beleg oder eine explizite Zertifizierung tragen;
aktualisiere entsprechend die Formulierungen in den Abschnitten mit den Phrasen
"stop when a leaf is answerable from one piece of code evidence or one
stakeholder fact." und "Each leaf is [ANSWERED] (with file:line evidence) or
[OPEN] (with Category, Ask role...)" damit beide Stellen dieselbe, restriktive
Regel verwenden.
---
Outside diff comments:
In `@skill/socratic-code-theory-recovery/references/examples.md`:
- Around line 167-188: The file contains duplicate question IDs: the headings
"### Q5.1: What test debt exists?" and "### Q5.1: What technical debt is the
team already tracking?" must be unique; change the second heading to "### Q5.2:
What technical debt is the team already tracking?" and update any in-file
references or cross-links that point to the old Q5.1 identifier (search for
"Q5.1" occurrences and adjust to "Q5.2" where they refer to the second question)
so build-time stable IDs remain unique.
---
Nitpick comments:
In `@website/public/llms.txt`:
- Around line 6375-6380: The duplicated fixed second-level enumeration
(Q1.1–Q5.5) should be replaced with a single canonical reference to the
contracts source instead of repeating the list: remove the hard-coded list in
website/public/llms.txt and add a short SSOT pointer like "See canonical
enumeration in contracts.json (contract `#493`)" and, if desired, a concise note
that the second-level nodes are fixed (Q1.1–Q5.5) to preserve intent; ensure any
mention of the second-level enumeration across the repo refers to
contracts.json/#493 to avoid drift.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
Run ID: cc560d7e-a8ea-4ab8-9fb7-de5885345a75
📒 Files selected for processing (21)
docs/all-anchors.adocdocs/brownfield-workflow.adocdocs/brownfield-workflow.de.adocdocs/socratic-recovery-skill.adocdocs/socratic-recovery-skill.de.adocplugins/semantic-anchors/skills/socratic-code-theory-recovery/SKILL.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/prompts/phase-1-question-tree.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/arc42.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/cockburn-use-cases.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/iso-25010.mdplugins/semantic-anchors/skills/socratic-code-theory-recovery/references/output-schema.mdskill/socratic-code-theory-recovery/SKILL.mdskill/socratic-code-theory-recovery/prompts/phase-1-question-tree.mdskill/socratic-code-theory-recovery/references/arc42.mdskill/socratic-code-theory-recovery/references/cockburn-use-cases.mdskill/socratic-code-theory-recovery/references/examples.mdskill/socratic-code-theory-recovery/references/iso-25010.mdskill/socratic-code-theory-recovery/references/output-schema.mdwebsite/public/data/contracts.jsonwebsite/public/llms.txt
Comment on lines
+69
to
70
| Start with five root questions about the bounded context. Their *second level is fixed*: every run emits the same prescribed set of sub-questions — the six PRD elements (Q1.1–Q1.6), six specification categories (Q2.1–Q2.6), the twelve arc42 chapters (Q3.1–Q3.12), the eight ISO/IEC 25010 characteristics plus a priority question (Q4.1–Q4.9), and five risk categories (Q5.1–Q5.5). Free, code-driven decomposition applies only *below* that fixed level. The fixed level keeps Q-IDs stable — Q3.7 is always the Deployment View — so trees from different runs can be diffed node-by-node. | ||
|
|
Contributor
There was a problem hiding this comment.
Kanonische Quelle für die feste Enumeration fehlt
In Line 69-70 und erneut in Line 93-106 wird die komplette Q1.1–Q5.5-Enumeration lokal ausgeschrieben, aber ohne expliziten Verweis auf die kanonische Contract-Definition. Das erhöht das Drift-Risiko zwischen Doku und Contract bei späteren Änderungen. Bitte hier klar auf die kanonische Quelle verweisen.
Also applies to: 93-106
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/brownfield-workflow.adoc` around lines 69 - 70, Die lokal
ausgeschriebene Enumeration Q1.1–Q5.5 (inkl. Q3.1–Q3.12 und Q4.1–Q4.9) fehlt
eine Verlinkung zur kanonischen Contract-Definition; aktualisiere beide Stellen,
an denen die feste Ebene ausgeschrieben ist, so dass unmittelbar nach der
Beschreibung ein klarer Verweis auf die offizielle Contract-Quelle steht (z. B.
ein eindeutiger Contract-Identifier/URL oder ein Verweisstext wie "siehe
Canonical Question Contract <name/id>"), und ergänze optional einen kurzen
Hinweis, dass Q-IDs stabil sind (z. B. "Q3.7 = Deployment View") damit künftig
kein Drift zwischen dieser Dokumentation und dem Contract entsteht.
Comment on lines
+67
to
68
| Mit fünf Wurzelfragen zum Bounded Context starten. Ihre *zweite Ebene ist fix*: jeder Lauf erzeugt denselben vorgegebenen Satz an Unterfragen — die sechs PRD-Elemente (Q1.1–Q1.6), sechs Spezifikationskategorien (Q2.1–Q2.6), die zwölf arc42-Kapitel (Q3.1–Q3.12), die acht ISO/IEC-25010-Merkmale plus eine Prioritätsfrage (Q4.1–Q4.9) und fünf Risikokategorien (Q5.1–Q5.5). Freie, code-getriebene Zerlegung gilt nur *unterhalb* dieser fixen Ebene. Die fixe Ebene hält Q-IDs stabil — Q3.7 ist immer die Verteilungssicht —, sodass Bäume verschiedener Läufe Knoten für Knoten verglichen werden können. | ||
|
|
Contributor
There was a problem hiding this comment.
Kanonische Quelle für die feste Enumeration nicht referenziert
Die feste Q1.1–Q5.5-Liste wird in Line 67-68 und Line 91-103 vollständig lokal wiederholt, aber ohne expliziten Verweis auf die kanonische Contract-Quelle. Das macht spätere Inkonsistenzen wahrscheinlicher. Bitte die kanonische Quelle direkt referenzieren.
Also applies to: 91-103
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/brownfield-workflow.de.adoc` around lines 67 - 68, Die wiederholte feste
Enumeration (Q1.1–Q5.5, inklusive Q3.7 als Verteilungssicht) muss mit der
kanonischen Contract-Quelle verlinkt werden: ergänze in der kurzen Beschreibung
bei "zweite Ebene ist fix" und in der vollständigen Liste (die zweite Stelle der
Wiederholung) jeweils einen eindeutigen Verweis/Zitat (z. B. Contract-Name,
Version und URL oder AsciiDoc xref/anchor) zur offiziellen Quelle, so dass
Leserinnen direkt zur autoritativen Definition springen können und
Inkonsistenzen vermieden werden.
| === Phase 1 — Build the Question Tree | ||
|
|
||
| The skill prompts the LLM to recursively decompose five questions about a bounded context (Problem/Users, Specification, Architecture, Quality Goals, Risks). Each leaf is classified: | ||
| The skill prompts the LLM to build a Question Tree from five root questions about a bounded context (Problem/Users, Specification, Architecture, Quality Goals, Risks). Their second level is fixed — every run emits the same enumerated nodes (Q1.1–Q5.5: six PRD elements, six specification categories, the twelve arc42 chapters, the eight ISO/IEC 25010 characteristics plus a priority question, five risk categories), so Q-IDs are stable and trees from different runs can be diffed node-by-node. Free, code-driven decomposition happens only below that fixed level. Each leaf is classified: |
Contributor
There was a problem hiding this comment.
Single-Source-of-Truth für die Q-Enumeration wird unterlaufen
In Line 12 und erneut im Tabellenabschnitt Line 193-199 wird die feste Knoten-Enumeration im Skill-Doc selbst ausgeschrieben. Für den Skill sollte diese Definition aus einer kanonischen Contract-Quelle referenziert werden, um Divergenzen zu vermeiden.
Also applies to: 193-199
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/socratic-recovery-skill.adoc` at line 12, The document hard-codes the
fixed Question Tree enumeration (Q-IDs like Q1.1–Q5.5, the six PRD elements,
twelve arc42 chapters, the eight ISO/IEC 25010 characteristics, etc.) in the
prose and table sections, which breaks Single Source of Truth; change the docs
to reference and/or include the canonical contract data instead of literal
lists: replace the explicit enumeration in the "Question Tree"/Q-IDs text and
the table block that repeats those entries with a generated include or template
call that pulls the authoritative enumeration from the canonical
contract/metadata source (the same JSON/YAML/constants that define the Q-IDs),
and add a simple validation step in the doc build to fail if the included
enumeration and the contract diverge so the "Q-IDs"/Question Tree and table
remain in sync.
| === Phase 1 — Question Tree aufbauen | ||
|
|
||
| Der Skill weist das LLM an, fünf Fragen zum Bounded Context (Problem/User, Spezifikation, Architektur, Qualitätsziele, Risiken) rekursiv zu zerlegen. Jedes Blatt wird klassifiziert: | ||
| Der Skill weist das LLM an, aus fünf Wurzelfragen zum Bounded Context (Problem/User, Spezifikation, Architektur, Qualitätsziele, Risiken) einen Question Tree zu bauen. Ihre zweite Ebene ist fix — jeder Lauf erzeugt dieselben enumerierten Knoten (Q1.1–Q5.5: sechs PRD-Elemente, sechs Spezifikationskategorien, die zwölf arc42-Kapitel, die acht ISO/IEC-25010-Merkmale plus eine Prioritätsfrage, fünf Risikokategorien), sodass Q-IDs stabil sind und Bäume verschiedener Läufe Knoten für Knoten verglichen werden können. Freie, code-getriebene Zerlegung passiert nur unterhalb dieser fixen Ebene. Jedes Blatt wird klassifiziert: |
Contributor
There was a problem hiding this comment.
Kanonische Contract-Quelle für die feste Knotenliste fehlt
Die fixe Q1.1–Q5.5-Enumeration wird in Line 12 sowie in Line 193-199 lokal wiederholt. Für den Skill sollte diese Definition auf die kanonische Contract-Quelle verweisen, statt sie mehrfach auszuschreiben, um Drift zu verhindern.
Also applies to: 193-199
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/socratic-recovery-skill.de.adoc` at line 12, The repeated explicit
enumeration of the fixed Question Tree nodes (the Q1.1–Q5.5 list referenced in
the "Question Tree" description and the duplicate block later) must be replaced
by a canonical reference: remove the hard-coded list text and instead reference
or include the single authoritative contract/source (the canonical contract for
the Skill) so the document points to that source for the fixed node list; update
both occurrences that mention "Q1.1–Q5.5" and the repeated fixed-node paragraph
to use an AsciiDoc include or xref to the canonical contract (or a named
"Socratic Recovery Skill" contract identifier) and keep the explanatory text
about stable Q-IDs and free decomposition unchanged.
| ### Q5.2: What test debt exists? | ||
| ### Q5.1: What test debt exists? | ||
|
|
||
| ``` |
Contributor
There was a problem hiding this comment.
Fenced Code Block mit Sprachkennung ergänzen (MD040).
Der Codeblock startet ohne Language-Tag. Bitte z. B. ```text ergänzen, damit der Linter sauber durchläuft.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 169-169: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@plugins/semantic-anchors/skills/socratic-code-theory-recovery/references/examples.md`
at line 169, Der fehlende Language-Tag am Fenced-Code-Block verursacht MD040;
ergänze unmittelbar nach den drei Backticks des betreffenden Blockbeginns im
examples.md einen Language-Identifier (z.B. ```text oder ```markdown) damit der
Linter den Block korrekt erkennt und MD040 verschwindet; suche den ungetaggten
Block um Zeile 169 und füge den Tag ein.
- examples.md: two Q5 example leaves both used the bare ID Q5.1. Both are technical-debt examples, so they become third-level leaves Q5.1.TestDebt and Q5.1.TrackedDebt (CodeRabbit suggested Q5.2, but Q5.2 is "security risks" — that would mislabel them). - iso-25010.md: the priority question was still tagged Q4.0; the fixed level defines it as Q4.9. - output-schema.md and phase-2-synthesize.md claimed the tree "is renumbered on every re-run", which contradicts the now-fixed second level. Reconciled: the fixed second level (Q1.1-Q5.5) is stable, third-level Q-IDs are run-specific, and the tree is a temporary intermediate artifact that is not shipped — that is why Q-IDs stay out of the synthesized docs. - Clarified the decomposition stop rule: a leaf is small enough to answer from one piece of code evidence, or to pose as one precise stakeholder question — so "answerable from a stakeholder fact" no longer reads as if it could be [ANSWERED]. Not changed: CodeRabbit also asked every doc to reference one canonical source for the Q1.1-Q5.5 enumeration. Declined — the enumeration lives in a JSON contract, a copy-paste skill prompt, and AsciiDoc pages; there is no include mechanism across those formats, and LLM-Coding#494/LLM-Coding#495 deliberately put a self-contained copy in each artifact. The MD040 lint nit is pre-existing file style, out of scope. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
Author
CodeRabbit review — addressedPushed 330fea8. Fixed:
Declined, with reason:
|
This was referenced May 17, 2026
rdmueller
pushed a commit
that referenced
this pull request
May 17, 2026
…[OPEN] Closes #498. A recovery run reduced arc42 Chapter 10 (Quality Requirements) to two [OPEN] pointers, which an independent arc42 review graded RED. The Socratic process was treating all of Quality as team-only knowledge. It is not. Quality-goal *priority/ranking* is team knowledge (Q4.9, [OPEN]); quality *scenarios* — what the system measurably does today — are usually code-derivable. Made the split operative (it previously lived only as a "rule of thumb" in references/iso-25010.md, with nothing enforcing it): - contract (#493) + phase-1 prompt: Q4 quality scenarios are [ANSWERED] where code shows measurable behaviour (timeouts, truncation limits, budgets, retry policies, the Q3.8 threats and test concept); only the ranking is [OPEN]; never invent a target number. - iso-25010.md: new section distinguishing a literal-threshold scenario (fully [ANSWERED], cite file:line) from a mechanism-only one (scenario derived, target value [OPEN]); explicit Q3.8 evidence reuse. - arc42.md: Q3.10 row now defines the Q4 -> Chapter 10 relationship. - phase-2-synthesize.md: Chapter 10 carve-out — synthesized from the [ANSWERED] Q4 scenarios plus the Q4.9 ranking, never just an [OPEN] pointer; "No information" only legitimate if Q4 produced no answered scenario at all. - examples.md: added an [ANSWERED] quality-scenario leaf (a literal 3-second timeout) alongside the existing mechanism/[OPEN]-target pair. Also fixed the German contract's stop-rule wording to match the EN one from the #497 CodeRabbit pass (was still "Stakeholder-Fakt"). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #493, closes #494, closes #495.
Why
Across four reverse-engineering runs on the same codebase, the question tree came out at 105 / 60 / 57 leaves, with whole role-sections silently dropped. "Anchors as guides" does not constrain the tree's shape, and unstable Q-IDs make trees from different runs impossible to diff.
What
The tree's second level is now fixed — the same enumerated node set on every run, emitted even when a node's only leaf is
[OPEN]or[ANSWERED: not applicable]:Q1.1-Q1.6— six PRD elementsQ2.1-Q2.6— six specification categoriesQ3.1-Q3.12— the twelve arc42 chapters, in arc42 orderQ4.1-Q4.8— the eight ISO/IEC 25010 characteristics;Q4.9priorityQ5.1-Q5.5— five risk categoriesFree, code-driven decomposition continues only below the fixed level. Q-IDs become stable —
Q3.7is always the Deployment View — so trees diff node-by-node.The three issues land together because the contract, the brownfield page and the skill all described free decomposition and would otherwise compete:
contracts.json: thesocratic-code-theory-recoverycard rewritten (template + templateDe) as the canonical enumeration.phase-1-question-treeprompt,SKILL.md, and thereferences/(arc42, iso-25010, cockburn-use-cases, output-schema, examples) reframed from "guides" to the fixed level. Named use-case sub-trees now nest under their fixed node —Q2.PUC.*→Q2.2.PUC.*,Q2.SUC.*→Q2.3.SUC.*. Thesocratic-recovery-skillpage (EN/DE) is brought in line. Plugin mirror auto-synced by the pre-commit hook.Notes
docs/all-anchors.adocregenerated (was stale — missing recent anchors).Test plan
npm run buildsucceeds;/brownfield,/socratic-recovery-skill,/contractsrenderllms.txtshows the rewritten socratic-code-theory-recovery contractQ2.PUC/Q2.SUCleft without the fixed-node prefix🤖 Generated with Claude Code
Summary by CodeRabbit
Dokumentation
Refactor